
Filesets and the Fileset Menu

                                               version: 0.2.0
                                               created: 07/26/99 {03:46:54 pm}
                                           last update: 11/21/2001 {13:25:37 PM}


Filesets are lists of files that Alpha uses for multiple-file searches and
tag searches, among other things.  Typically, a user will set up several
different file sets, for example:

   all html files in a web site
   all source files in a programming project
   a local image of a remote cvs code repository
   all files on a remote ftp site
   all documents in a multi-part LaTeX document

A fileset can be as simple as 'All files recursively contained within a
given directory' or there can be much more complex membership rules.

Alpha provides a menu into which you may wish to place your commonly used
filesets: each fileset will appear as a submenu whose label is the name of
the fileset (which you specify when you create the fileset), and whose
contents are the names of the files within the fileset.  Selecting an item
in the menu will open the file for editing.  For each fileset you create,
you may also decide not to place it in the menu but rather to have it
hidden.  Hidden filesets are fully functional in every way to every other
part of Alpha which interacts with filesets; they are simply not shown in
the menu.

In fact Alpha creates some 'hidden' filesets which you can use.  One of
these is a fileset containing all recently used files; another is a fileset
containing all currently open windows.  The reason these filesets are
'hidden' is that they are updated very frequently, and already feature in
the Windows and Recent-Files menus, so there is little need for them to
appear in the fileset menu.

	  	 Activating the Fileset menu

The Fileset menu, like all of Alpha's menus, is activated in the dialog
"Config --> Preferences --> Menus".  Check the 'Fileset Menu' box among
the global menus, and it should appear in the menu bar.  For new users it
is automatically activated by default, so it should already be in the menu
bar.  If icons are used in your menu bar, this menu looks like a stack of
overlapping documents.  If icons are not used, then this menu is simply
called 'Fileset'.

	  	 Getting started

As an introductory example this section describes how to create a new 
fileset with all files in a folder.

 Create a new fileset by selecting 'New Fileset' in the Utilities submenu 
  of the Fileset Menu.
 You are now asked which type of fileset you want. Select 
  'From Directory' to create a fileset with the files in a folder.
 You are now asked to give the fileset a name. Let's give it the name 'My 
  fileset'.
 Then you are asked to select the folder for the fileset.  Select a
  folder/directory containing files you might like quick access to.
 Next you are asked to give a pattern for the fileset specifying which files 
  in the folder to include in the fileset. To include all files use the 
  default pattern '*'. See the section File Patterns in the Alpha manual to 
  learn about how to specify file patterns.
 Next you are asked to specify a list of patterns for files you want to 
  exclude from the fileset but which were included by the file pattern you 
  just specified. Leave this blank for now.
 Finally you are asked if you want save the fileset. Doing so will make 
  Alpha keep the fileset the next time you run Alpha.

Alpha now builds a new submenu of the Fileset menu called 'My fileset'
with all the files in the folder you selected.  Selecting a file in the
submenu will open the file in Alpha.

Your fileset can also be used for multi-file searching. In the Find dialog 
when selecting multi file searching, you can choose to search the files in 
your fileset.

You can also do multi file search and replace in your fileset, by 
selecting 'Replace In Fileset' in the Utilities menu.

	  	  Fileset types

Some fileset types require that you give file patterns specifying which 
files to include in the fileset. Read the Section File Patterns in the 
Alpha manual to learn about how to specify file patterns.

	From Directory          

The basic type: create a fileset of all files in a given folder which match
a given pattern.  You have to specify:

 The folder with the files.
 A file pattern matching the files to include.
 A list of patterns of files to exclude.
                        
	From Hierarchy          

Takes the above one step further and allows filesets to include all files
in a nested set of folders.  You have to specify:

 The base folder with the files.
 The depth of nested folders.
 A file pattern matching the files to include.

	Recurse In              

A simplification of 'From Hierarchy' which includes all files contained in
the given base folder.  Hence you only need to specify: 

 The base folder with the files.

	From Open Windows       

Make a fileset containing all currently open windows.

	Codewarrior             

Query the Codewarrior IDE for a list of all files in the current project.

	Think                   

Query the Symantec Project Manager for a list of all files in the current
project.

	Tex                     

Make a fileset of all parts of a multi-part TeX/LaTeX document.  Alpha's
LaTeX mode understands these and will automatically send your TeX
application the base .tex/.ltx file when you select 'Typeset' on any
component part.  Details about TeX filesets can be found in the LaTeX mode
documentation.

	Ftp                     

Make a fileset of files at a remote machine via ftp.  You have to specify:

   Host, path (optional), user id, and password
   A regular expression (not a file pattern!) matching the files to include.

	Procedural              

Make a fileset from a Tcl procedure.  This type requires that you write a
Tcl procedure which returns a list of paths to all files in the fileset. 
When you create a new procedural fileset Alpha puts an empty procedure
(with the correct name!)  in your global preferences file.  You must then
write the body of this procedure.  Procedural filesets are completely
dynamic and will not appear in the Fileset menu.

	  	  Non-text files

By default only text files are included in the fileset.  If the flag
'Include Non Text Files' is set, the fileset menu may contain files Alpha
is not designed to open; these are sent to the Finder which will open them
using whichever application created them.  A common use of this feature is
a hierarchical fileset containing a complete C or C++ project.  Selecting
any project source file will open that file for editing, and selecting the
project file/debugging symbol file/...  will open that using appropriate
tool (Symantec Project Manager or Codewarrior IDE or Debugger,) Another
use can be to include images in a home page so you can quickly open them
when you want to change the graphics.

	  	  Fileset menu cache

Rather than rebuilding the Fileset menu every time you launch Alpha, the
menu is saved in a cache file.  This is to speed up launching of Alpha as
building the filesets may take a while if there are many of them. 
Therefore the fileset submenus may become out of date and you have to
rebuild them.  You can rebuild a single fileset either using 'Update
Current Fileset' or 'Update A Fileset' or rebuild them all using 'Rebuild
All Filesets'.

	  	  Current Fileset

Some functions that use filesets operate on the 'current' fileset.  The
current file set can be selected in the 'Choose' submenu of the Utilities
menu.  There is also a flag 'Auto Adjust Fileset' which will switch the
current filesets whenever the fileset menu is used to open a file.
	  	
	======================================================================


	  	 Fileset Utilities Menu

There are various common fileset-related actions which you may wish to carry
out.  Some built-in actions are listed in the 'Fileset -> Utilities' menu,
and others may be added by features you have activated.  The first half of 
the menu contains the fundamental fileset operations, and the second half
less commonly used operations, including operations added by other
features.

	Edit Filesets          

allows you to modify all details of all the filesets you have created.  It
also allows you to edit additional information which some packages might
attach to each fileset (for example, whether to use a version control
system for the files, or whether to use a particular tab size setting).

	New Fileset            

Create a new fileset of one of the above six standard types (others may be
added by writing your own Tcl code, see below.)

	Delete Fileset         

Remove a fileset, permanently if desired.

	Print Fileset          

Print all files in a fileset

	Update Current Fileset  

Re-build the current fileset from scratch

	Update A Fileset (hold down option)

Lets you choose a fileset to rebuild.

	Rebuild All Filesets    

Total menu rebuild, including all ftp filesets.

	Choose                  

A menu from which to set the current fileset.

	Hide Fileset            

If you have many filesets, some of which are only used for searching
purposes, you can remove them from the menu.

	Fileset Flags           

See below for an explanation of the flags.   

	Find Tag                

See Tags for information on this and the following item.

	Create Tag File 

The items below may not all work for all types of filesets.

	Browse Fileset         

Opens a browser window containing all fileset items, from which any can be
opened.

	Close Entire Fileset   

Close all windows which belong to a given fileset.

	Fileset To Alpha       

Convert all text files in a fileset to Alpha's creator.

	Open Entire Fileset    

Open all the windows contained in the fileset for editing.

	Open Fileset Folder    

Tells the Finder to open the base folder which contains a fileset.

	Rename Fileset         

Change a fileset's name

	Replace In Fileset     

Global search and replace in all files.  Use this item with care!

	Stuff Fileset          

Use 'Drop Stuff' to compress all the files in the fileset.  For filesets
which are based on a directory hierarchy, you will be given the option of
compressing the entire hierarchy (as opposed to just the files listed in
the fileset).

	Word Count              

Count all words in a fileset.


	  	  Fileset Preferences

The following flags may be set:

	Auto Adjust Fileset     

Opening a file from the menu will adjust current fileset

	Include Non Text Files  

Files not of type 'TEXT' may be in the menu.

	Indent Fileset Items    

Visually format submenus if appropriate.

	Sort Fileset Items      

Force alphabetical ordering for all filesets

	Sort Filesets By Type   

Structure the fileset menu in a user-defined, type- dependent fashion; see 
the "Personalisation" section below.

	  	  TeX filesets

The following items will be added to the utilities menu if you use 
TeX filesets:

	Extract Eps BoxSizes    

Search all document parts for included eps graphics, extract bounding box
information from the .eps files and insert it explicitly into the document
(can lead to much quicker typesetting).

	Delete Eps Box Sizes    

Remove all the above bounding box information

	Hierarchical Bib Files  

Bibliography files may \input others, so they should be searched (the
default is not to do this, because .bib files may be enormous).

	  	  Binding keys to common fileset operations

Different users tend to use filesets in very different ways, so we
cannot create a useful common set of key bindings for the 'most
common' fileset operations.  If you wish to create a personalised
key-binding for a particular item in the utilities menu, then
use 'Config -> Preferences -> Edit Prefs File', and add a line like
the following to that file:

	Bind 'o' <z> [list filesetMenu::utilsProc "" openFilesetFolder]

When you restart (or immediately if you 'evaluate' the line), your
key-binding will take effect.  The above will bind 'ctrl-o' to the
'open fileset folder' action.
	  	
	======================================================================


	  	 Additional fileset information


Some packages may attach pieces of data to each fileset.  Examples could be
the default tab size to use for a fileset (useful if the files use a
different value to your own global default), or the type of version control
under which the files are registered.

Authors of Tcl extensions to Alpha use the proc: fileset::attachNewInformation
to add such data.  It automatically appears in the 'Edit Filesets' dialog.
The packages which currently attach such information, and/or provide
additional fileset functionality are as follows (list current only at the
time of writing):

	  	  Recent files multi menu

If you use this more sophisticated version of the recent files menu, you
will find a new checkbox 'Use As Recent Files Group' by each fileset in the
'Edit' dialogs.  If ticked for a fileset, then recently edited files from
that fileset are listed separately in the recent files menu.

	  	  Fileset Tab Preference

If activated, you can select a default tab size to use for all files in a
given fileset.

	  	  Fileset Encoding Preference

Alphatk and Alpha 8 understand different types of textual encoding in which
files may be saved.  This feature allows you to specify a default encoding 
to use for editing files in each fileset.

	  	  Fileset Ftp Mirror

If you would like copies of all files in a fileset to be mirrored on a
remote ftp site, this feature allows you to attach information about the
site (site address, path, username and password) to a fileset, and then
provides a new menu item 'Update Fileset Mirror' in the fileset utilities
menu which automatically sychronizes the contents of the remote site with
any changed documents.


	  	 Personalisation

As well as adjusting the aforementioned flags, the fileset menu allows
complete user control of the structure of the menu in the following way:
Set the 'Sort Filesets By Type' flag, and set the variable
"filesetSortOrder" as follows:

The structure of this variable dictates how the fileset menu is structured:
       
	'{pattern p}' 
    
Lists all filesets which match 'p'

	'-' 

Adds a separator line

	'{list of types}' 

Lists all filesets of those types.

	'{submenu name sub-order-list}' 
    
Adds a submenu with name 'name' and recursively adds filesets to that
submenu as given by the sub-order.
           
Leading, trailing and double separators are automatically removed.

For example, the default value of this variable (more as an example than 
anything else) is:

	set filesetSortOrder { {pattern *Core} {pattern Packages} \
	  {pattern Menus} {pattern Modes} {pattern Preferences} \
	  - {tex} - {pattern *.cc} {submenu Headers {pattern *.h}} \
	  - {fromDirectory think codewarrior ftp \
	  fromOpenWindows fromHierarchy} * }

You can and should over-ride this in your global preferences file (copy and
paste from here into a "prefs.tcl" file, then make your changes).

	  	
	======================================================================


	  	 Known problems with Alpha 7.x


Alpha 7.x has hard-coded limits on the maximum number of items in a dialog. 
The "Edit Filesets" dialog, if you have many filesets (and have activated
packages which attach additional information to each fileset), can easily
surpass those limits, and the action will simply fail.  In this case you
will have to use the "Utilities --> Edit A Fileset" menu item.  These
hard-coded limits have been massively increased in Alpha 8.

